home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 1 Issue 2 / PDCD-1 - Issue 02.iso / _editors / editors / _zap / !Zap / Docs / E-Windows < prev    next >
Text File  |  1994-08-13  |  10KB  |  269 lines
  1. *************************************************************************
  2. * >E-Windows    Documents a Zap window block format.            *
  3. *************************************************************************
  4.  
  5. By convention, window blocks are pointed to by R8. However, as with files,
  6. the pointer address may change whenever a window is created. Thus, as for
  7. files, block pointers should be changed to window offsets for storing. Use
  8. the calls Zap_GetWindOff, Zap_ConvWindOff. The first two paragraphs of E-File
  9. hold if you replace 'file block' by 'window block' and R9 by R8. Please read
  10. the E-File file first.
  11.  
  12. Window block offsets have names beginning 'w_'. See E-Library for a complete
  13. list. Each window determines uniquely a file via the offset w_file.
  14.  
  15. As far as Zap and the extension modes are concerned, a Zap text window
  16. consists of a rectangle of characters. Coordinates are usually given in terms
  17. of row and column in R2,R3. Ie, by convention,
  18.  
  19.     R2=column offset from left hand edge, in characters.
  20.     R3=offset in lines from the top of the display, in lines.
  21.     
  22. R2 includes the margin which may contain the line numbers. The line numbers
  23. are handled automatically by zap. Thus a window looks like:
  24.  
  25.             0    w_margin    w_width
  26.               0 -------------------------
  27.             |    |        |
  28.             |    |        |
  29.             |    |        |
  30.             |    |        |
  31.             |    |        |
  32.            w_height    -------------------------
  33.  
  34. The quantity w_width-w_margin is usually stored in the mode dependent byte
  35. w_bpl (bytes per line). However for byte/word modes this is not true, and the
  36. number of bytes in the file that the line represents is stored in w_bpl. It
  37. is up to the mode concerned to fill in w_bpl.
  38.  
  39. The are two ways of numbering lines in Zap. These are called PHYSICAL line
  40. numbers and LOGICAL line numbers. The PHYSICAL line number of a file offset
  41. is the line offset from the top of the file in the display. Ie, it is the 'y'
  42. value of that character starting from 0 on the first line. All line counts
  43. start from zero within zap, though the number w_stline is added before the
  44. line number is printed on screen for the user. The LOGICAL line number of a
  45. file offset is determined entirely by the extension mode and Zap doesn't care
  46. what it is. For example, in text mode it is taken to be the number of
  47. carriage returns before the offset (ie the physical line it would have been
  48. on if the display hadn't been wrapped). In BASIC mode, it is taken to be the
  49. actual number of the line as encoded in the program.
  50.  
  51. A further complication is that the window text display is cached. The start
  52. of the cached area is used as a reference point for working out the file
  53. offset of a given physical or logical line number. Thus it is not necessary
  54. to start counting from the start of the file to find out where a line is. All
  55. line references work locally from this value, which is the start of the
  56. cached display, which is where the user is likely to be editing! The calls
  57. Zap_FindOffset and Zap_OffLineCol use this fact. These calls use the mode
  58. entry points 'e_cln*'. Thus these entry points should use this reference
  59. point. Thus the mode will need a piece of code (usually called cln_backward)
  60. for tracing lines backwards up the file. (See the docs on these entry
  61. points).
  62.  
  63. The cache itself consists of a number of lines of width w_txtw. This width is
  64. usually w_width rounded up to the next multiple of 8. An extension mode need
  65. not usually concern itself with this cache unless it is drawing its own
  66. display. See the mode entry point e_redrawline in which you are asked to fill
  67. a line in the cache. I reserve the right to change the format of the cache,
  68. so don't access it directly.
  69.  
  70. The window block offsets are described below. Use E-Library to set up the
  71. definitions.
  72.  
  73. w_handle
  74. Window handle for this window or -1 if the window has been deleted and this
  75. block is now 'dead'. Dead blocks should be skipped if you are going through
  76. the windows in sequence.
  77.  
  78. w_minx
  79. w_miny
  80. w_maxx
  81. w_maxy
  82. w_scrollx
  83. w_scrolly
  84. w_infront
  85. w_windowflags
  86. These are as for a wimp window block. See PRM if in doubt. You can use
  87. the code MOV R1,R8:SYS "XOS_GetWindowState" to update these values.
  88.  
  89. w_file
  90. Gives the file offset of the associated file. Use Zap_ConvFileOff to convert
  91. this to a file pointer in R9. This is done automatically for you by
  92. Zap_ConvWindOff.
  93.  
  94. w_format
  95. Gives the display format flags and the mode the window is in. See E-Flags for
  96. details.
  97.  
  98. w_width
  99. Width of window in columns (including the margin).
  100.  
  101. w_height
  102. Height of window in lines.
  103.  
  104. w_txt
  105. Address of text cache.
  106.  
  107. w_txth
  108. Number of lines claimed for txt cache. Each line consists of w_txtw number of
  109. characters followed by a foreground mask (of length w_txtw) and then a
  110. background mask (of length w_txtw). Thus the size of the cache is
  111. w_txth*w_txtw*3. w_txtw*3, the 'actual length' of a cached line is stored in
  112. the variable w_txtlen. See e_redraw line for more details.
  113.  
  114. w_txtw
  115. Width of a text cache line in characters. Must be a multiple of 8. This does
  116. not include the foreground and background masks. See w_txtlen.
  117.  
  118. w_txtn
  119. Number of lines cached in the txt cache.
  120.  
  121. w_coff
  122. Reference point giving the file offset of the start of the first cached
  123. physical line.
  124.  
  125. w_cline
  126. Reference point giving the physical line number (first line 0) of the start
  127. of the first cached physical line.
  128.  
  129. w_clogl
  130. As for w_cline but gives the logical line number.
  131.  
  132. w_tab
  133. Gives the coltab width.
  134.  
  135. w_tabc
  136. Gives the character code tab mask (x4) eg &09090909. Set this to the same as
  137. w_cr if you want the tabs to be invisible.
  138.  
  139. w_cr
  140. Gives the line terminator mask (x4) eg &0A0A0A0A.
  141.  
  142. w_flags
  143. Gives the flags status for this window. See E-Flags. When a window is created
  144. the default value is taken from opt_flags.
  145.  
  146. w_title
  147. Points to the window title string.
  148.  
  149. w_bpl
  150. Mode dependent word. Usually stores the width of the display in characters.
  151. Byte mode stores the number of bytes shown on each line etc.
  152.  
  153. w_margin
  154. Width of the left hand margin in characters (including any line numbers - so
  155. this may be non zero even if the user has not set a margin).
  156.  
  157. w_rl
  158. Height in pixels of each character including the line spacing.
  159.  
  160. w_rw
  161. Width in pixels of each character.
  162.  
  163. w_rh
  164. Height in pixels of each character excluding line spacing.
  165.  
  166. w_addr
  167. Address to show in margin for file offset 0.
  168.  
  169. w_stline
  170. Line number to show in margin for line offset 0.
  171.  
  172. w_titlelen
  173. w_titbuf
  174. w_titlen
  175. Used internally for title update.
  176.  
  177. w_mwidth
  178. User required margin width before space for line numbers added.
  179.  
  180. w_tabchar
  181. User required tab character code x4 (eg &09090909) before tab visibility
  182. taken into account. w_tabc contains the one actually being used.
  183.  
  184. w_linesp
  185. User required line spacing in 1/8ths char.
  186.  
  187. w_savedo
  188. Used internally by Zap_DoCommand to store the offset of the first shiftable
  189. line after a command, and by Zap_SaveWinStatus to store the file offset of
  190. the character whose position should remain fixed when the window is
  191. recreated.
  192.  
  193. w_savedl
  194. Used internally by Zap_DoCommand to store the physical line number of the
  195. first shiftable line after a command, and by Zap_SaveWinStatus to store the y
  196. offset from the top of the window in pixels of the character whose position
  197. should remain fixed when the window is recreated.
  198.  
  199. w_savedc
  200. Used internally by Zap_DoCommand to store the number of physical lines text
  201. after the first shiftable line should be shifted down after a command
  202. (signed).
  203.  
  204. w_savedh
  205. Used internally by Zap_DoCommand to save the window height before a sequence
  206. of commands was performed.
  207.  
  208. w_savedlc
  209. Used internally by Zap_DoCommand and Zap_SaveWinStatus
  210.  
  211. w_wrapwidth
  212. Wordwrap width.
  213.  
  214. w_togminx
  215. w_togminy
  216. w_togmaxx
  217. w_togmaxy
  218. These save the 'small' window position for the toggle size key (scG).
  219.  
  220. w_txtlen
  221. Actual length of a cache line including the foreground and background masks.
  222.  
  223. w_palette
  224. Pointer to current redraw palette. Its format depends on the redraw mode and
  225. the Zap mode and the number of colour it has. You should access colours via
  226. the call Zap_ModeColour and should not look at this directly. For debugging
  227. puposes it may help to know than in DSA mode it points to a list of bitmap
  228. masks and in VDU mode a list of 24 bit colour values (&BBGGRRZZ).
  229.  
  230. w_pwind
  231. w_pline
  232. w_pcol
  233. w_poff
  234. w_ploff
  235. w_pwidth
  236. This is the 'cursor block' of the 'point' position. This is the file offset
  237. of the current 'input' position in the file when the file does not contain
  238. the cursor. It is updated when the cursor moves from one file to another.
  239. This position is usually marked with an empty square cursor. See the file
  240. E-Cursors for what the variables store - w_poff is the most useful giving the
  241. file offset of the 'point'. w_pwind is set up as the window offset of this
  242. current window. This in its self is not useful but enables you to call
  243. cursor handling routines with R10=R8+w_pwind (provided the routine doesn't
  244. use any of the 'old' offsets).
  245.  
  246. w_saveds
  247. Used internally by Zap_DoCommand. Saves the first file offset to be updated
  248. on screen after the command has finished.
  249.  
  250. w_modedata
  251. This points to a block which stores the mode dependant data handled by Zap.
  252. This includes the mode palettes. Use the calls Zap_ModeData and
  253. Zap_ModeColour to read/write this block. It's format changes regularly!
  254.  
  255. w_res10-w_res16
  256. Reserved words
  257.  
  258. w_mode0-w_mode15
  259. Mode words. Each mode has one word in each in window in which to store the
  260. options pertaining to that mode. If bit 10 of the flags in the modes e_mode
  261. entry point is SET then instead of storing data, the mode word holds
  262. a pointer to a block of data in Zap's heap (or 0 if the block has not been
  263. created). In this case, the first word of the block MUST contain the length
  264. of the block (including the first word). The block will be copied
  265. automatically by Zap, for example, on a New View. The block will be freed
  266. automatically when the window is closed. The block is created automatically
  267. when a window is opened, and filled with the contents of the default block
  268. stored in the !Config file and accessed via Zap_Read/Write Var - see E-Vars.
  269.